home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 1 Issue 2 / PDCD-1 - Issue 02.iso / _utilities / utilities / 001 / mnemosyn / StubsHack / !Help
Text File  |  1994-09-02  |  4KB  |  136 lines
  1. StubsHack version 1.00 01 Sep 1994
  2. ----------------------------------
  3.  
  4.  
  5.  
  6.  
  7.  
  8. Introduction
  9. ------------
  10.  
  11. This is a C library which uses an idea of Martin Ebourne's to enable you
  12. to very easily redirect all calls to the ANSI memory allocation
  13. functions (malloc, realloc, calloc, free) to your own function. This
  14. could be used to add heap-checking to the malloc functions.
  15.  
  16. The important point is that this happens at *runtime*, so even if you
  17. link your program with a library which was compiled years ago, all
  18. malloc calls within the library will be redirected.
  19.  
  20. See my 'HeapGraph' library for an example of how to use StubsHack.
  21.  
  22.  
  23.  
  24.  
  25. Installation
  26. ------------
  27.  
  28. You should move the StubsHack directory into your C path. Don't move any
  29. headers into an existing .h. directory, as they are refered to as
  30. 'StubsHack.<headername>.h' in the source.
  31.  
  32. I find this to be a much simpler way of organising C libraries than
  33. changing C$Path etc. It also protects against problems when header files
  34. from different libraries have the same name.
  35.  
  36. The actual library is 'C:StubsHack.o.SHLib'.
  37.  
  38.  
  39.  
  40.  
  41. How StubHack works  
  42. ------------------
  43.  
  44. When a program is linked with the object file Stubs, all calls to the
  45. standard C functions like printf, malloc etc. are made (by the linker)
  46. to branch (usually with link) to an address within Stubs. 
  47.  
  48. The instruction at this address isn't the start of the function,
  49. however. It is just a branch to the malloc/etc function inside the
  50. SharedCLib module. 
  51.  
  52. This branch is set to point to the right place within the SharedCLib
  53. module when the program is run, before the main() function is started.
  54. In this way, the SharedCLibrary is used by many different applications
  55. at the same time.
  56.  
  57. StubsHack simply changes the branch instruction in stubs to be a branch
  58. to a different function. All users of ANSI C functions continue to call
  59. this instruction, so they all end up going to the new function.
  60.  
  61.  
  62.  
  63. What you can do with StubsHack 
  64. ------------------------------
  65.  
  66. As well as providing low-level functions to read/change the destination
  67. of any stubs branch instruction, StubsHack provides a general functions
  68. which should be used to intercept/take over the four ANSI C allocation
  69. functions malloc, realloc, calloc and free.
  70.  
  71. It provides two things:
  72.  
  73. 1) A way of changing the contents of the stubs branch instructions for
  74.    malloc/realloc/callos/free, so that it points to one of your
  75.    functions.
  76.  
  77. 2) The address (normally within the sharedClibrary) of the original
  78.    malloc/realloc/calloc/free function.
  79.  
  80. The second enables you to make a 'wrapper' function for the ANSI
  81. re/m/calloc/free functions - eg. you redirect all malloc calls to your
  82. own MallocWrap function, and within MallocWrap, you use the actual
  83. shared C lib function pointers to call the original SharedCLib function.
  84.  
  85. This could be used, for eg., to add heap-verification to your program,
  86. by storing special info in each malloc block, and checking this info is
  87. ok when freeing the block. 
  88.  
  89. For example, the Mnemosyne library does just this to provide
  90. heap-checking and limited protection against overwriting memory etc by
  91. having wrapping functions for malloc/realloc/calloc/free, but only by
  92. #define-ing malloc to mnem_malloc etc, so you have to recompile all
  93. files and libraries used in the program to get the checking. 
  94.  
  95. Obviously, recompiling your source is easy, but recompiling DeskLib (for
  96. eg.) is not a trivial matter.
  97.  
  98. With StubsHack, it would be easy to make something like Mnemosyne which
  99. would check all memory allocations without needing recompilation of all
  100. libraries etc. In fact, this has been done, and will hopefully be
  101. included with Mnemosyne when it is released.
  102.  
  103.  
  104.  
  105.  
  106.  
  107. Other
  108. -----
  109.  
  110. All the contents of the StubsHack directory are ⌐ Julian Smith, 1994.
  111. Feel free to distribute it, but only distribute the original version. If
  112. you make any changes, please send them to me and I'll send them out with
  113. the next release.
  114.  
  115. Any suggestions/comments/bug fixes etc are very much welcomed.
  116.  
  117.  
  118.  
  119. - Julian Smith
  120.  
  121.  
  122. ------------------------
  123. julians@cogsci.ed.ac.uk
  124. ------------------------
  125.  
  126. or:
  127.  
  128. ------------------------
  129. Department of Psychology
  130. University of Edinburgh
  131. 7 George Square
  132. Edinburgh
  133. EH8 9JZ
  134. UK
  135. ------------------------
  136.